<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.6"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Percepio Trace Recorder: Usage</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectalign">
   <div id="projectname">Percepio Trace Recorder<span id="projectnumber">&#160;v4.9.2</span>
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.6 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(document).ready(function(){initNavTree('Usage-example.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>

<div class="header">
  <div class="headertitle"><div class="title">Usage</div></div>
</div><!--header-->
<div class="contents">
<p>This function enables tracing. To use the trace recorder, the startup must call <a class="el" href="trcRecorder_8h.html#a55cefe256f7bfcfa9085667696a1752d" title="Initializes the recorder data. xTraceInitialize() or xTraceEnable(...) must be called before any atte...">xTraceInitialize()</a> or xTraceEnable(...) before any RTOS calls are made (including "create" calls). This function should only be called after the timestamp source is properly initialized. If kernel services that generate trace data are called before that, an earlier call to <a class="el" href="trcRecorder_8h.html#a55cefe256f7bfcfa9085667696a1752d" title="Initializes the recorder data. xTraceInitialize() or xTraceEnable(...) must be called before any atte...">xTraceInitialize()</a> is necessary. Then call xTraceEnable(...) once the timestamp source is initialized.</p>
<p>This function enables tracing. To use the trace recorder, the startup must call <a class="el" href="trcRecorder_8h.html#a55cefe256f7bfcfa9085667696a1752d" title="Initializes the recorder data. xTraceInitialize() or xTraceEnable(...) must be called before any atte...">xTraceInitialize()</a> or xTraceEnable(...) before any RTOS calls are made (including "create" calls). This function should only be called after the timestamp source is properly initialized. If kernel services that generate trace data are called before that, an earlier call to <a class="el" href="trcRecorder_8h.html#a55cefe256f7bfcfa9085667696a1752d" title="Initializes the recorder data. xTraceInitialize() or xTraceEnable(...) must be called before any atte...">xTraceInitialize()</a> is necessary. Then call xTraceEnable(...) once the timestamp source is initialized.</p>
<p>Three start options are provided: </p><pre class="fragment">TRC_START: Starts the tracing directly. In snapshot mode this allows for 
starting the trace at any point in your code, assuming xTraceInitialize()
has been called in the startup. Can also be used for streaming without 
Tracealyzer control, e.g. to a local flash file system (assuming such a
"stream port", see trcStreamPort.h).

TRC_START_AWAIT_HOST: For streaming mode only. Initializes the trace recorder
if necessary and waits for a Start command from Tracealyzer ("Start Recording"
button). This call is intentionally blocking! By calling xTraceEnable with
this option from the startup code, you start tracing at this point and capture
the early events.

TRC_START_FROM_HOST: For streaming mode only. Initializes the trace recorder
if necessary and creates a task that waits for a Start command from
Tracealyzer ("Start Recording" button). This call is not blocking.
</pre><p> examples </p><pre class="fragment">Snapshot trace, from startup:
    &lt;board init&gt;
    xTraceEnable(TRC_START); // Will call xTraceInitialize()
    &lt;RTOS init&gt;

Snapshot trace, from a later point:
    &lt;board init&gt;
    xTraceInitialize();
    &lt;RTOS init&gt;
    ...
    xTraceEnable(TRC_START); // e.g., in task context, at some relevant event

Streaming trace, from startup (can only be used with certain stream ports):
&lt;board startup&gt;
xTraceInitialize();
&lt;RTOS startup&gt;
    xTraceEnable(TRC_START);

Streaming trace, from startup:
&lt;board init&gt;    
xTraceEnable(TRC_START_AWAIT_HOST); // Blocks!
&lt;RTOS init&gt;

Streaming trace, from a later point:
&lt;board startup&gt;
xTraceInitialize();
&lt;RTOS startup&gt;
    xTraceEnable(TRC_START);

Streaming trace, system executes normally until host starts tracing:
&lt;board startup&gt;
xTraceInitialize();
&lt;RTOS startup&gt;
xTraceEnable(TRC_START_FROM_HOST)
</pre> <dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramdir">[in]</td><td class="paramname">uiStartOption</td><td>Start option.</td></tr>
  </table>
  </dd>
</dl>
<dl class="retval"><dt>Return values</dt><dd>
  <table class="retval">
    <tr><td class="paramname">TRC_FAIL</td><td>Failure </td></tr>
    <tr><td class="paramname">TRC_SUCCESS</td><td>Success</td></tr>
  </table>
  </dd>
</dl>
<div class="fragment"> </div><!-- fragment --> </div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.6 </li>
  </ul>
</div>
</body>
</html>
